Installation

Install the {distill} package from CRAN:

install.packages("distill")

Clone the ala-labs repository to a local directory.

Build the website

We use a custom file to build the website. To build the website, run the code in R/ignition_sequence.R.

If successful, to see the built website navigate to your local file explorer and opening _site/index.html.

We use a custom file to build the website because we have added several bespoke features to the standard distill website format (like auto-updating lists in _people pages and a custom search toolbar). Adding these features means that using the recommended method by {distill} to use the Build Website tab in the Build pane no longer works. Only using rmarkdown::build_site() will also not work correctly.


When you build the website, the following things occur:

  1. All of the Rmd and md files in the root website directory will be rendered into HTML. Note, however, that markdown files beginning with “_” are not rendered (this is a convention to designate files that are included by top level documents, or in other words, distill knows not to overwrite these folders because they are important).

  2. Posts will be copied into the _site/posts sub-directory. Pages with post listings will be re-generated.

  3. The generated HTML files and any supporting files (e.g. CSS and JavaScript) are copied into the _site directory.

  4. The top 3 most recently written Posts will be added to the author’s _people page. (Note: For the website to build, ensure that all people who have authored a post have their own People page, even if this page is not accessible to the public)

The HTML files within the _site directory are built and ready to deploy as a standalone static website.

Publishing the website

The _site folder has all of the information needed for the static website. The ALA web hosting service has been told to publish what is in the _site folder on the master branch to .

When you are happy with changes or updates to the website, make sure your changes to the _site folder are pushed to the master branch.

Update the website

Website workflow

Updates to the website should be added to the dev branch of the GitHub repo. In the dev branch, any changes made will not be published to the existing website. The dev branch effectively works as a test site prior to deployment.

Add or edit content

Site Output and Navigation

The _site.yml controls the main website information and site navigation.

Elements can be edited to alter navigation paths. Here is one example of the navbar for the ALA Labs website:

---
navbar:
  logo:
    image: images/logos/ALA_Logo_Stacked_REV.png
    href: https://www.ala.org.au
  right:
    - text: "About"
      href: about.html
    - text: "Posts"
      href: posts.html
    - text: "Resources"
      menu:
        - text: "galah"
          href: galah.html
        - text: "ALA Labs Style Guide"
          href: test_style-guide.html
    - icon: fab fa-github
      href: https://github.com/AtlasOfLivingAustralia/science
---

Web Pages

Add top-level pages

Top-level web pages (the ones people see in the top navigation bar) are saved in the top-level folder by their page name (for example, the content for the About page is in about.Rmd).

Additional pages can be added by creating a new R Markdown page in the main website folder with the yaml header:

---
title: ""
description: |
  description-goes-here
output: 
  distill::distill_article:
    css: theme.css
---

Pages can then be added to the website by their text and href to the site navigation in _site.yml under navbar (see Site Output and Navigation)

Posts

Writing new posts

Posts are written in R markdown files. Post templates can be found in the templates folder.

To create a new post:

  1. Create a new folder in the _posts folder. The folder name should be the date and title of your article (for example, 2022-02-17_sunburst-plots-for-taxonomic-data

  2. In your new post folder, save your Post file. You are welcome to use a simple name for your Rmd file (for example, sunburst-plots.Rmd)

  3. Be sure that you have filled in all the necessary information about your post in the yaml header and in the author card section

  4. Write your post

  5. Render/Knit your document using the R/render_post.R document. Using the code in R/render_post.R allows you to avoid adding personal information to your Post (like your personal email in galah_config()). The most recently knitted version of your file is what will appear on the website

  6. When you are happy with your post, build the website. After the website it built, your rendered post should appear in the Posts listing page

Theme customisation

Distill uses a CSS framework that can be fully customised. CSS theme settings are in theme.css. See the Distill website page for instructions on how to edit additional website properties.

Some properties can be found in labeled sections, like settings for website fonts, header and footer sections. For example, website header settings can be found in the .distill-site-header section:

/*-- WEBSITE HEADER + FOOTER --*/
/* These properties only apply to Distill sites and blogs  */

.distill-site-header {
  --title-size:       18px;    
  --text-color:       #ff414b; /* edited */
  --text-size:        15px;
  --hover-color:      #dd424c; /* edited */
  --bkgd-color:       #ffd8db; /* edited */
}

Other properties are edited using custom CSS. These are (mostly) labelled and relate either to built-in distill html elements or html elements built in R/function.R.

Custom html elements using R functions

R/functions.R contains functions that create html elements within the ALA Labs website. R/functions.R uses the {htmlTools} package to write html code using R syntax.

For example, the following R function and html code are equivalent. They both will create a link of class = "article-link". This class name can be used with CSS in theme.css to edit the element style.

#<!-- html -->
#<a class = "article-link" href = "https://ala.org.au/">my text</a>
# R function
add_link_to_article <- function(title, url){
  tags$a(
    class = "article-link",
    href = url,
    "text"
  )
}

add_link_to_article(text = "my text", url = "https://ala.org.au/")

The benefits of writing R functions to create html elements are:

  1. Rather than trying to edit html elements that the Distill package runs in the back-end to build the website, adding html elements using R functions is easier and less prone to errors

  2. It is easier for people familiar in R to reuse and edit the content of existing html elements created by R functions

To use functions in the R/functions.R file on a specific website page or post, the following code block must be added below the YAML header

  ```{r, include=FALSE}
  library(htmltools)
  source("R/functions.R")

```

The ALA is made possible by contributions from its partners, is supported by NCRIS, is hosted by CSIRO, and is the Australian node of GBIF.

NCRIS logo CSIRO logo GBIF logo

This work is licensed under a Creative Commons Attribution 3.0 Australia License Creative Commons License

Copyright    Terms of Use    System Status